home *** CD-ROM | disk | FTP | other *** search
/ By Popular Request 2.0 / By Popular Request 2.0 (Arsenal Computer).ISO / amiga_6 / wbtitl14.lha / WBTitle / WBTitle14.doc < prev    next >
Text File  |  1995-05-29  |  11KB  |  260 lines
  1. WBTitle Documentation
  2. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  3. * Update: v1.4 - multi-locale version by Martin Kaim (Gwardar) 25-05-1995
  4.  
  5. * Note: Any parts of this doc file marked * were added or adapted by Gwardar
  6. * (read them to get a quick grasp of the changes to the previous version)
  7.  
  8. * Originally Designed and Implemented by Mark Thomas, fine-tuned by Gwardar
  9. This software is placed in the public domain.
  10. You may modify the program or use the code in anyway you see fit.
  11. I make no claims as to the code's fitness for use in any setting.
  12. I make no claims as to the program's fitness for use in any setting.
  13. Use the code or program at your own risk.
  14.  
  15. * Enhancements, bugfixes, Workbench multi-locale support code
  16. * by Gwardar.
  17.  
  18. * The entire risk of using this software is with the user. The author(s)
  19. * cannot be held liable for any possible damages arising from the
  20. * use of this software. Apply the usual four-page disclaimer ;->
  21.  
  22. Motivation
  23. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  24. I (Mark Thomas) was reading someone's message on Usenet when something he
  25. said made me come up with the idea for this program.  The actual technical
  26. notion came from comments in the docs for the VMM virtual memory
  27. program by Martin Apel.  Thanks for the clue on patching Intuition.
  28.  
  29. I also was concerned that there might not be any good source code
  30. example on how to do SetFunction() from C.  The source code for this
  31. program is in the archive.
  32.  
  33. * I (Gwardar) found that WBTitle v1.0 didn't work on non-English WB
  34. * locales; when I had adapted the source and recompiled it, I found it to
  35. * be really useful (after a display bug in the memory amount string had been
  36. * fixed, too).
  37.  
  38. * Shortly afterwards, I uploaded the update to Aminet. Some time later,
  39. * I got email asking me kindly to release a version with an executable
  40. * compiled for English WB locale, as my version wouldn't work with non-German
  41. * workbench settings. I first thought of doing so, but then I had a better
  42. * idea: only one executable for ALL languages would be much nicer.
  43.  
  44. * Thus, I added some sort of multi-locale WB support via tooltypes.
  45. * Now, WBTitle is very flexible (configurable to your needs) and has IMHO
  46. * been found a valuable tool on high-resolution WB screens (e.g. Retina-
  47. * equipped machines).
  48.  
  49.  
  50. Overview
  51. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  52. WBTitle is a program that lets you replace your Workbench title bar
  53. with just about any text you like.  It also gives you the facilities
  54. to put memory readings in the title bar.  At its simplest, you could
  55. replace the title bar with the same text that is already there, and
  56. in the exact same format.  But WBTitle allows you to do more. (see Features)
  57.  
  58. *** NEW: READ THIS ***
  59.  
  60. Installation
  61. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  62. Put 'WBTitle' where you like in your path. Choose one of 'WBTitle_e.info' or
  63. 'WBTitle_d.info' and put it in the same place as the executable under the
  64. name of 'WBTitle.info'.
  65.  
  66. Have a look at the tooltypes, adjust MATCH1 and MATCH2 according to this
  67. documentation. (The values in the supplied WBTitle(_e|_d).info files should
  68. work with standard English respectively German Workbench locale settings.)
  69.  
  70. Start WBTitle by double-clicking on it from Workbench. If started from
  71. a Shell it will not find its tooltypes (thus, it won't work) and also block
  72. your Shell until it is quit by running it again (from WB or another shell)).
  73.  
  74. The WB title should change to the configured string after at max a few
  75. seconds. If you don't like the way it looks, quit WBTitle, adjust the
  76. tooltypes, then start it again.
  77.  
  78. A good place to put 'WBTitle' and its icon is the 'WBStartup' drawer.
  79. Or, if you still don't like it, put it in the bin... 8-|
  80.  
  81. **********************
  82.  
  83. Features
  84. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  85. The title bar replacement is partitioned into three main parts,
  86. prefix, memory, and postfix.  They are combined in the order
  87. prefix-memory-postfix to make the title bar text.
  88.  
  89. The prefix is just a string of text that appears at the leftmost part
  90. of the title bar.  The memory consists of memory strings.  There can
  91. be several items in the memory section, shown shortly.  The postfix
  92. is simply some text that appears at the end of the title bar text.
  93.  
  94. As stated above, the memory can have several parts.  Each part is a
  95. memory reading (amount of free memory with a label).  The memory
  96. displays that are available are chip, fast, public, total, virtual,
  97. and retina.  Chip, fast, public, and total are normal Amiga memory
  98. options.  Virtual is for use with the VMM program for showing free
  99. virtual memory.  Retina is for use with a Retina graphics card for
  100. showing the amount of free graphics memory.
  101.  
  102. The memory reading consists of the memory value and a label (some
  103. text).  All labels come either before the memory value or after the
  104. memory value, which is determined by the LABELS option described
  105. below.
  106.  
  107.  
  108. Requirements
  109. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  110. * For the VMM virtual memory option to work, the library that comes
  111. * with VMM, "vmm.library", will have to be placed in LIBS:.
  112.  
  113. * Note: the memory string will ONLY be shown when VMM is active, e.g. its
  114. * port can be found in the system port list. As this is only checked once
  115. * on WBTitle startup, VMM memory won't appear in the memory string if VMM
  116. * is activated AFTER WBTitle has been initialized.
  117. * It's easy to handle this 'feature' ;-> if it's a problem to you:
  118. * quit WBTitle, start VMM, restart WBTitle.
  119. * The reasons for *not* checking if VMM is active every time the Workbench
  120. * title gets updated are:
  121. * i)   my laziness, as this would require some major modifications to the code
  122. * ii)  the additional overhead especially on slow machines (68000)
  123. * iii) VMM's sometimes weird behaviour when trying to quit it (wouldn't
  124. *      quit totally, so the port might still be there while the virtual
  125. *      memory function was actually deactivated)
  126. *      Note: this was the case with old VMM versions - haven't tested v3.1
  127. *      yet as I just downloaded it today from Aminet ;-)
  128.  
  129. * For the Retina gfx board memory option to work, you need a properly
  130. * set up Retina software package and functional hardware.
  131.  
  132. Options
  133. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  134. All the options are specified in the tool types to keep the program
  135. size small.  Tool types are entered from the Workbench by clicking
  136. on the WBTitle icon and choosing Information... from the Icons menu.
  137. Here are the tool types:
  138.  
  139. *** NEW: READ THIS ***
  140.  
  141. MATCH1
  142.  
  143. The first of the two match strings used to determine your Workbench window
  144. title (allows the patch to distinguish the workbench window title from
  145. other window titles so that they don't get changed).
  146. Defaults to: "Amiga"
  147.  
  148. MATCH2
  149.  
  150. The second match string.
  151. Defaults to: "graphics mem"
  152.  
  153. (There is no order when matching strings to window titles, so MATCH2 may
  154. specify a part of the original title coming *before* the part that MATCH1
  155. specifies just as well as *after*.)
  156.  
  157. The more specific you are when giving these match strings, the better
  158. the patch can decide whether a window title to be set is Workbench's or not.
  159.  
  160. You *have* to specify *either* *both* or *none* of the MATCH1/MATCH2
  161. tooltypes, otherwise the patch will probably not work as you'll get a
  162. mixture of your own custom match string and the (other) default string.
  163.  
  164. If you specify none of these two tooltype arguments, the patch will fail
  165. on all other than the standard English locale WB setup!
  166.  
  167. Caveat:
  168. If you specify *both* of the strings to be e.g. " ", *all* window titles
  169. containing " " (that is, any number of spaces) will change to WBTitle's
  170. replacement string when they are next refreshed (depends on the application
  171. when/how often that happens). To stop this, run WBTitle again (thus removing
  172. the patch), edit the tooltype entries, save the changes, and restart WBTitle
  173. a second time. It should not be too difficult to find a set of MATCH strings
  174. suiting your specific needs.
  175.  
  176. **********************
  177.  
  178. PREFIX
  179.  
  180. Lets you set the prefix text.
  181. Default: "PREFIX="
  182.  
  183. SUFFIX
  184.  
  185. Lets you set the suffix text.
  186. Default: "SUFFIX="
  187.  
  188. LABELS
  189.  
  190. Lets you specify if the memory labels are placed before or after
  191. the memory values so that you can do things like "Chip: 1,232,848"
  192. or "1,012 KB Chip Mem".
  193.  
  194. MEMORDER
  195.  
  196. Allows you to set the order of the memory readings, as well as which
  197. memory values are to be used.  It consists of a several letters that
  198. you arrange in the order you want the readings.  Each letter stands
  199. for a particular memory type:  C for chip, F for fast, P for public,
  200. T for total, V for virtual, and R for Retina.
  201. Default: "MEMORDER=CVPR"
  202.  
  203. CHIP
  204.  
  205. Lets you set the text that appears with the chip memory reading.
  206. Default: "CHIP= Chip"
  207.  
  208. FAST
  209.  
  210. Lets you set the text that appears with the fast memory reading.
  211. Default: "FAST= Fast"
  212.  
  213. PUBLIC
  214.  
  215. Lets you set the text that appears with the public memory reading.
  216. Default: "PUBLIC= Public"
  217.  
  218. TOTAL
  219.  
  220. Lets you set the text that appears with the total memory reading.
  221. Default: "TOTAL= Total"
  222.  
  223. VIRTUAL
  224.  
  225. Lets you set the text that appears with the virtual memory reading.
  226. Default: "VIRTUAL= Virtual"
  227. * Text will only appear if VMM is installed and ACTIVE (running)!
  228.  
  229. RETINA
  230.  
  231. Lets you set the text that appears with the retina memory reading.
  232. Default: "RETINA= Retina"
  233. * Text will only appear if Retina is installed correctly!
  234.  
  235. THOUSANDSEP
  236.  
  237. Lets you choose whether memory values have a separator before each
  238. thousands group or not.  If this is set, your memory values would
  239. * have the format "1.228.352".  If this is not specified, your memory
  240. values would have the format "1228352".
  241. Default: there is no default
  242.  
  243. SEPARATOR
  244.  
  245. Allows you to set the character used to separate the thousands groups
  246. in memory values.  This is to allow for other countries.
  247. * Default: "SEPARATOR=," (English locale)
  248.  
  249. UNITS
  250.  
  251. Allows you to set the accuracy of the memory values.  It's easiest
  252. to show an example.  If you have a memory value 1,228,352 and this
  253. is set to 1, then that's exactly what you see, 1,228,352.  If you
  254. wanted to see only how many kilobytes you have free, you can set the
  255. value to 1024 and you would see 1,199, since that's the number of
  256. kilobytes in 1,228,352.  So whatever value is the real memory
  257. setting, it gets divided by this value.  Setting to 0 will end up as
  258. a setting of 1 so that divides by zero are avoided.
  259. Default: "UNITS=1"
  260.